<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<title>File Class - Advanced usage - Fuel Documentation</title>
	<link href="../../assets/css/main.css" media="screen" rel="stylesheet" />
	<script type="text/javascript" src="../../assets/js/jquery-1.4.4.min.js"></script>
	<script type="text/javascript" src="../../assets/js/nav.js"></script>
	<script type="text/javascript" src="../../assets/js/highlight.pack.js"></script>
	<script type="text/javascript">
		$(function() {
			show_nav('classes', '../../');
		});
		hljs.tabReplace = '    ';
		hljs.initHighlightingOnLoad();
	</script>
</head>
<body>

	<header>
		<h1>Fuel Documentation</h1>
	</header>

	<div id="main-nav"></div>

	<section id="content">
		<h2>Advanced usage</h2>

		<section>
			<h3 id="intro">Introduction</h3>

			<p>
				Aside from the basic static <a href="usage.html">usage</a> of the File class there are also more
				complex options available. The first are <strong>areas</strong> which are basically basepaths it
				cannot act outside of and have some configuration options. And when using the File class's methods
				on an area they will return objects wrapping directories &amp; files.
			</p>

			<article>
				<h2 id="areas">Areas</h2>

				<h3 id="areas_intro">Introduction</h3>
				<p>
					File areas are used to influence file system behaviour. By setting basic restrictions you can
					set boundaries to allow a flexible use inside those limits without worrying about unauthorized
					access of files and directories.
				</p>

				<h3 id="area_config">Configuration</h3>
				<p>
					By default file areas have unlimited access through all directories. There are two ways to set
					these configuration values. The quickest way is to pass an array intro the
					File::factory method.
				</p>

				<pre class="php"><code>$config = array(
	'basedir'		=> DOCROOT.'uploads',
	'use_locks'		=> true,
);

$area = \File::factory($config);</code></pre>

				<p>
					A more centralized way is by defining an area (or more) inside you File config file. To do so,
					copy <em>core/config/file.php</em> into <em>app/config/file.php</em> (or create a new one) and
					define your area inside the <em>'areas'</em> array. Now you can get the area by supplying the
					string identifier to the File::factory method.
				</p>

				<pre class="php"><code>// inside app/config/file.php
'areas' => array(
	'my_area' => array(
		'basedir'		=> DOCROOT.'uploads',
		'use_locks'		=> true,
	),
),

// Now get the area

$area = \File::instance('my_area');
				</code></pre>

				<h3 id="area_usage">Usage</h3>

				<p>
					There are 2 ways to use areas in the File class. <br />
					The first is to use areas in a static context, supply a File_Area instance or identifier to the
					function you're calling.
				</p>

				<pre class="php"><code>// Read the contents of a directory
try
{
	$dir = File::read_dir('somedir', 0, null, 'my_area');
}
catch(\FileAccessException $e)
{
	// Operation failed
}
</code></pre>

				<p>The second way is to call the functions directly from the area itself.</p>

				<pre class="php"><code>// Get the area
$area = File::instance('my_area');

try
{
	$dir = $area->read_dir('somedir', 0, null);
}
catch(\FileAccessException $e)
{
	// Operation failed
}
</code></pre>

			</article>

			<article>
				<h2 id="file_handers">Files &amp; directories as objects: File Handlers</h2>

				<p>
					<a href="handlers.html">Read about File Handlers.</a>
				</p>
			</article>
		</section>

	</section>

	<section id="footer">
		<p>
			<a href="http://fuelphp.com">Fuel</a> is released under the MIT license.<br />
			&copy; 2010 - 2011 Fuel Development Team
		</p>
	</section>

</body>
</html>